home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 501-525 / disk_521 / a68k / a68k.doc next >
Text File  |  1992-05-06  |  31KB  |  721 lines
  1.     A68k - a freely distributable assembler for the Amiga
  2.  
  3.             by Charlie Gibbs
  4.  
  5.              with special thanks to
  6.         Brian R. Anderson and Jeff Lydiatt
  7.  
  8.                 (Version 2.70 - February 25, 1991)
  9.  
  10.      Note:  This program is Freely Distributable, as opposed to Public
  11. Domain.  Permission is given to freely distribute this program provided no
  12. fee is charged, and this documentation file is included with the program.
  13.  
  14.      This assembler is based on Brian R. Anderson's 68000 cross-
  15. assembler published in Dr. Dobb's Journal, April through June 1986.
  16. I have converted it to produce AmigaDOS-format object modules, and
  17. have made many enhancements, such as macros and INCLUDE files.
  18.  
  19.      My first step was to convert the original Modula-2 code into C.
  20. I did this for two reasons.  First, I had access to a C compiler, but
  21. not a Modula-2 compiler.  Second, I like C better anyway.
  22.  
  23.      The executable code generator code (GetObjectCode and MergeModes)
  24. is essentially the same as in the original article, aside from its
  25. translation into C.  I have almost completely rewritten the remainder
  26. of the code, however, in order to remove restrictions, add enhancements,
  27. and adapt it to the AmigaDOS environment.  Since the only reference book
  28. available to me was the AmigaDOS Developer's Manual (Bantam, February
  29. 1986), this document describes the assembler in terms of that book.
  30.  
  31.  
  32. RESTRICTIONS
  33.  
  34.      Let's get these out of the way first:
  35.  
  36.       o The verification file (-v) option is not supported.  Diagnostic
  37.     messages always appear on the console.  They also appear in the
  38.     listing file, however (see extensions below).  You can produce
  39.     an error file by redirecting console output to a file - the
  40.     line number counter and final summary are displayed on stderr
  41.     so you can still see what's happening.
  42.  
  43.       o The file names in the INCLUDE directory list (-i) must be
  44.     separated by commas.  The list may not be enclosed in quotes.
  45.  
  46.       o Labels assigned by EQUR and REG directives are case-sensitive.
  47.  
  48.       o Strange things will happen if your source code (including
  49.     INCLUDE files and macro expansions) exceeds 32,766 lines.
  50.     Tough darts.  Break up your source file.  Can you actually
  51.     read that monster?  :-)
  52.  
  53.       o The following directives are not supported, and will be flagged
  54.     as invalid op-codes:
  55.  
  56.         OFFSET
  57.         NOPAGE
  58.         LLEN
  59.         PLEN
  60.         NOOBJ
  61.         FAIL
  62.         FORMAT
  63.         NOFORMAT
  64.         MASK2
  65.  
  66.     I feel that NOPAGE, LLEN, and PLEN should not be defined within
  67.     a source module.  It doesn't make sense to me to have to change
  68.     your program just because you want to print your listings on
  69.     different paper.  The command-line switch "-p" (see below) can
  70.     be used as a replacement for PLEN; setting it to a high value
  71.     (like 32767) is a good substitute for NOPAGE.  The effect of
  72.     LLEN can be obtained by running the listing file through an
  73.     appropriate filter.
  74.  
  75.  
  76. EXTENSIONS
  77.  
  78.      Now for the good stuff:
  79.  
  80.       o Labels can be any length that will fit onto one source line
  81.     (currently 127 characters maximum).  Since labels are stored
  82.     on the heap, the number of labels that can be processed is
  83.     limited only by available memory.
  84.  
  85.       o The first character of a label can be '@' if the next character
  86.     is not numeric (this avoids confusion with octal constants).
  87.     This provides compatibility with the Lattice C compiler.
  88.  
  89.       o Since section data and user macro definitions are stored in
  90.     the symbol table (see above), they too are limited only by
  91.     available memory.  (Actually, there is a hard-coded limit of
  92.     32,767 sections, but I doubt anyone will run into that one.)
  93.  
  94.       o The only values a label cannot take are the register names -
  95.     A68k can distinguish between the same name used as a label,
  96.     instruction name or directive, macro name, or section name.
  97.  
  98.       o Section and user macro names appear in the symbol table dump,
  99.     and will also be cross-referenced.  Their names can be the same
  100.     as any label (see above); they will be listed separately.
  101.  
  102.       o INCLUDEs and macro calls can be nested indefinitely, limited
  103.     only by available memory.  The message "Secondary heap
  104.     overflow - assembly terminated" will be displayed if memory
  105.     is exhausted.  You can increase the size of this heap using
  106.     the -w switch (see below).  Recursive macros are supported;
  107.     recursive INCLUDEs will, of course, result in a loop that
  108.     will be broken only when the heap overflows.
  109.  
  110.       o The EVEN directive forces alignment on a word (2-byte)
  111.     boundary.  It does the same thing as CNOP 0,2.
  112.     (This one is left over from the original code.)
  113.  
  114.       o Backward references to labels within the current CODE section
  115.     will be converted to PC-relative addressing with displacement
  116.     if this mode is legal for the instruction.  This feature is
  117.     disabled by the -n switch.
  118.  
  119.       o If a MOVEM instruction only specifies one register, it is
  120.     converted to the corresponding MOVE instruction.  Instructions
  121.     such as MOVEM D0-D0,label will not be converted, however.
  122.     This feature is disabled by the -n switch.
  123.  
  124.       o ADD, SUB, and MOVE instructions will be converted to ADDQ,
  125.     SUBQ, and MOVEQ respectively if possible.  Instructions coded
  126.     explicitly (e.g. ADDA or ADDI) will not be converted.  This
  127.     feature is disabled by the -n switch.
  128.  
  129.       o ADD, CMP, SUB, and MOVE to an address register are converted to
  130.     ADDA, CMPA, SUBA, and MOVEA respectively, unless (for ADD, SUB,
  131.     or MOVE) they have already been converted to quick form.
  132.  
  133.       o ADD, AND, CMP, EOR, OR, and SUB of an immediate value are
  134.     converted to ADDI, ANDI, CMPI, EORI, ORI, and SUBI respectively
  135.     (unless the address register or quick conversion above has
  136.     already been done).
  137.  
  138.       o If both operands of a CMP instruction are postincrement mode,
  139.     the instruction is converted to CMPM.
  140.  
  141.       o Operands of the form 0(An) will be treated as (An) except for
  142.     the MOVEP instruction, which always requires a displacement.
  143.     This feature is disabled by the -n switch.
  144.  
  145.       o The SECTION directive allows a third parameter.  This can be
  146.     specified as either CHIP or FAST (upper or lower case).  If
  147.     this parameter is present, the hunk will be written with the
  148.     MEMF_CHIP or MEMF_FAST bit set.  This allows you to produce
  149.     "pre-ATOMized" object modules.
  150.  
  151.       o The synonyms DATA and BSS are accepted for SECTION directives
  152.     starting data or BSS hunks.  The CHIP and FAST options (see
  153.     above) can also be used, e.g. BSS name,CHIP.
  154.  
  155.       o The following synonyms have been implemented for compatibility
  156.     with the Aztec assembler:
  157.         CSEG is treated the same as CODE or SECTION name,CODE
  158.         DSEG is treated the same as DATA or SECTION name,DATA
  159.         PUBLIC is treated as either XDEF or XREF, depending on
  160.             whether or not the symbol in question has been
  161.             defined in the current source module.
  162.             A single PUBLIC directive can name a mixture
  163.             internally- and externally-defined symbols.
  164.  
  165.       o The ability to produce Motorola S-records is retained from the
  166.     original code.  The -s switch causes the assembler to produce
  167.     S-format instead of AmigaDOS format.  Relocatable code cannot
  168.     be produced in this format.
  169.  
  170.       o Error messages consist of three parts.
  171.         The position of the offending line is given as a line
  172.     number within the current module.  If the line is within a
  173.     macro expansion or INCLUDE file, the position of the macro
  174.     call or INCLUDE statement in the outer module is given as
  175.     well.  This process is repeated until the outermost source
  176.     module is reached.
  177.         Next, the offending source line itself is listed.
  178.         Finally, the errors for that line are displayed.  A flag
  179.     (^) is placed under the column where the error was detected.
  180.  
  181.       o Named local labels are supported.  These work the same as the
  182.     local labels supported by the Metacomco assembler (nnn$) but
  183.     are formed in the same manner as normal labels, except that
  184.     they must be preceded by a backslash (\).
  185.  
  186.       o The following synonyms have been implemented for compatibility
  187.     with the Assempro assembler:
  188.         ENDIF is treated the same as ENDC
  189.         = is treated the same as EQU
  190.         | is treated the same as ! (logical OR)
  191.  
  192.       o Quotation marks (") can be used as string delimiters
  193.     as well as apostrophes (').  Any given string must begin
  194.     and end with the same delimiter.  This allows such statements
  195.     as the following:
  196.         MOVEQ    "'",D0
  197.         DC.B    "This is Charlie's assembler."
  198.     Note that you can still define an apostrophe within a string
  199.     delimited by apostrophes if you double it, e.g.
  200.         MOVEQ    '''',D0
  201.         DC.B    'This is Charlie''s assembler.'
  202.  
  203.       o If any errors are found in the assembly, the object code file
  204.     will be scratched, unless you include the -k (keep) flag on
  205.     the command line.
  206.  
  207.       o The symbols .A68K, .a68k, .a68K, and .A68k are automatically
  208.     defined as SET symbols having absolute values of 1.
  209.     This enables a source program to determine whether it is
  210.     being assembled by this assembler, and is effectively
  211.     insensitive as to whether or not it is checked in upper case.
  212.  
  213.       o A zeroth positional macro parameter (\0) is supported.  It
  214.     is replaced by the length of the macro call (B, W, or L,
  215.     defaulting to W).  For instance, given the macro:
  216.  
  217.         moov    MACRO
  218.             move.\0    \1,\2
  219.             ENDM
  220.  
  221.     the macro call
  222.  
  223.             moov.l    d0,d1
  224.  
  225.     would be expanded as
  226.  
  227.             move.l    d0,d1
  228.  
  229.       o If an INCLUDE file doesn't generate any code and no listing
  230.     file is required (including suppression of the listing using
  231.     NOLIST), it won't be read again in pass 2.  The statement
  232.     numbers will be bumped to keep in proper alignment.  This
  233.     can really speed up assemblies that INCLUDE lots of EQUates.
  234.  
  235.       o The ORG directive is supported.  It works like RORG, except
  236.     that it takes the actual address to be jumped to, rather
  237.     than an offset from the start of the current section.
  238.     The given address must be in the current section.
  239.     As far as A68k is concerned, the only real difference
  240.     between ORG and RORG is that the ORG value must be
  241.     relocatable, while the RORG value must be absolute.
  242.  
  243.       o Branch (Bcc, including BRA and BSR) instructions will be
  244.     converted to short form if possible.  Shortening a branch
  245.     may bring other branches within range of shortening - this
  246.     can set up a ripple effect, and A68k may not catch all
  247.     branches that could theoretically be optimized.  Any branches
  248.     which A68k misses (there shouldn't be too many under normal
  249.     circumstances) can be displayed by specifying the -f switch
  250.     (see below).  Branch optimization is disabled by the -n switch.
  251.  
  252.       o The INCBIN directive allows the contents of any file to be
  253.     included in A68k's object code output.  Its format is the same
  254.     as the INCLUDE directive, but the file can contain any data
  255.     at all, printable or not.  Rather than being processed as
  256.     source code by the assembler, the entire contents of the file
  257.     is copied directly to the current position in the object code
  258.     output file with no reformatting whatsoever.  The effect is
  259.     the same as if DC statements whose constants represent the
  260.     file's contents were inserted in place of the INCBIN directive.
  261.  
  262.       o The opcode TTL is accepted as a synonym for TITLE.
  263.  
  264.       o A command-line option (-g) causes A68k to treat any undefined
  265.     symbol as XREF.
  266.  
  267.       o The register list in a MOVEM instruction can be an
  268.     immediate operand which specifies the actual mask bits.
  269.  
  270.  
  271. THE SMALL CODE / SMALL DATA MODEL
  272.  
  273.      Version 2.4 implements a rudimentary small code/data model.
  274. It consists of converting any data reference to one of the following
  275. three addressing modes:
  276.  
  277.     address register indirect with displacement using a
  278.         specified address register, defaulting to A4
  279.         (for references to the DATA or BSS section)
  280.     program counter indirect with displacement
  281.         (for references to the CODE section)
  282.     absolute word
  283.         (for absolute and 16-bit relocatable values)
  284.  
  285. These conversions do not take place unless a NEAR directive is
  286. encountered.  The NEAR directive can take one operand, which
  287. must be either an address register or a symbol which has been
  288. equated (using EQUR) to an address register.  Register A7 (SP)
  289. may not be used.  If no register is given, A4 is assumed.
  290.  
  291.      Conversion is done for all operands until a FAR directive
  292. is encountered.  NEAR and FAR directives can occur any number
  293. of times, enabling conversion to be turned on and off at will.
  294.  
  295.      Backward references which cannot be converted (e.g. external
  296. labels declared as XREF) will remain as absolute long addressing.
  297. All forward references are assumed to be convertible, since during
  298. pass 1 A68k has no way of telling whether conversion is possible.
  299. If conversion turns out to be impossible, invalid object code will
  300. be generated - an error message ("Invalid forward reference") will
  301. indicate when this occurs.
  302.  
  303.      Although the small code/data model can greatly reduce the
  304. size of assembled programs, several restrictions apply:
  305.  
  306.       o Small code and small data models are active simultaneously.
  307.     You can't have one without the other, since during pass 1
  308.     A68k doesn't know whether forward references are to CODE
  309.     or to DATA/BSS.
  310.  
  311.       o Programs can consist of a maximum of two sections,
  312.     one CODE, the other DATA or BSS.  If you try to define
  313.     a third section, the message "Too many SECTIONs" will
  314.     be displayed.  The NEAR directive is active only within
  315.     the CODE section.
  316.  
  317.       o While the NEAR directive is active, external labels (XREF)
  318.     must be declared before they are used, CODE section references
  319.     must be with 32K of the current position (i.e. expressible as
  320.     PC-relative), and DATA/BSS section references must be in the
  321.     first 64K of the DATA/BSS section (i.e. expressible as
  322.     address register indirect with displacement).  Any instructions
  323.     which do not satisfy these requirements cannot be detected in
  324.     pass 1, so A68k has no choice but to display an error message
  325.     in pass 2 ("Invalid forward reference") which in this case
  326.     indicates that invalid code has been generated.  To properly
  327.     assemble such instructions, you can temporarily disable
  328.     conversion with a FAR directive, then resume afterwards
  329.     with another NEAR directive.
  330.  
  331.       o Conversion cannot be done for references between modules.
  332.     All external references must be left as absolute long.
  333.  
  334.       o A68k assumes that the base register (normally A4) points to
  335.     the start of the DATA/BSS section plus 32768 bytes.  (This
  336.     assumed offset can be changed by the -m command-line parameter.)
  337.     The register must be preloaded with this value before executing
  338.     any code converted by the NEAR directive.  One way to do this
  339.     is to code the instruction that loads the register prior to
  340.     the NEAR directive.  Another way is to use a MOVE.L with
  341.     immediate mode, which is never converted.  Here are examples
  342.     of the two methods:
  343.  
  344.         LEA    data+32768,a4        NEAR
  345.         NEAR    ;defaults to A4        MOVE.L    #data+32768,a4
  346.         <remainder of code>            <remainder of code>
  347.         BSS                BSS
  348.     data:                data:
  349.         <data areas>            <data areas>
  350.         END                END
  351.  
  352.      I'll be the first to admit that this is a very crude and ugly
  353. implementation.  I hope to improve it in future versions.
  354.  
  355.  
  356. FILES
  357.  
  358.      A68k uses the following files:
  359.  
  360.       o The source code file - this file contains the program to be
  361.     assembled.  This file is an ASCII text file whose last line
  362.     must be an END statement.
  363.  
  364.       o The object code file - this file is created by A68k, replacing
  365.     any previous version which may exist.  If any errors are
  366.     encountered during the assembly, this file will be scratched,
  367.     unless the -k (keep) switch is specified (see below).
  368.     Although this file is normally written in AmigaDOS format,
  369.     the -s switch (see below) will cause it to be written in
  370.     Motorola S-record format instead.
  371.  
  372.       o The listing file - this file is optionally created by A68k
  373.     and contains a listing complete with page headings (including
  374.     form feeds), generated object code, and error messages if any.
  375.     It is suitable for feeding to a printer.
  376.  
  377.       o An equate file - this file is optionally created by A68k
  378.     and consists of a leading comment line followed by EQU
  379.     statements, one for each symbol encountered by A68k whose
  380.     value is absolute.  This file is only created if the -e
  381.     command-line switch is specified (see below).
  382.  
  383.       o A header file - if requested, this file is read by A68k
  384.     immediately prior to the source code file.  It treated
  385.     exactly as if it were requested by an INCLUDE statement
  386.     at the front of the source file, but is selected only if
  387.     the -h command-line switch is specified (see below).
  388.  
  389.       o Include files are selected by INCLUDE directives within the
  390.     source file, and are inserted in the source code in place
  391.     of the INCLUDE directive itself.  A68k first searches the
  392.     current directory for INCLUDE files; the -i command-line
  393.     switch (see below) specifies additional directories which
  394.     can be searched.
  395.  
  396.  
  397. FILE NAMES
  398.  
  399.      The names of the above files can be explicitly specified.
  400. However, A68k will generate default file names in the following cases:
  401.  
  402.       o If the -o switch is omitted, a default name will be assigned
  403.     to the object code file.
  404.  
  405.       o If the -e switch is specified with no file name, a default
  406.     name will be assigned to the equate file.
  407.  
  408.       o If the -l or -x switch is specified with no file name, a
  409.     default name will be assigned to the listing file.
  410.  
  411. A default name is generated by deriving a stem name from the source
  412. code file name, and appending .o for an object code file name (.s
  413. if the -s switch is specified to produce Motorola S-records), .equ
  414. for an equate file name, or .lst for a listing file name.  The stem
  415. name consists of all characters of the source file name up to the
  416. last period (or the entire source file name if it contains no period).
  417. Here are some examples:
  418.                            Default names
  419.             --------------------------------------------
  420.     Source file    Object file    Equate file    Listing file
  421.     -----------    -----------    -----------    ------------
  422.     myprog.asm    myprog.o    myprog.equ    myprog.lst
  423.     myprog        myprog.o    myprog.equ    myprog.lst
  424.     new.prog.asm    new.prog.o    new.prog.equ    new.prog.lst
  425.  
  426.  
  427. HOW TO USE A68k
  428.  
  429.      The command-line syntax to run the assembler is as follows:
  430.  
  431.     a68k <source file name>
  432.          [<object file name>]
  433.          [<listing file name>]
  434.         [-d[[!]<prefix>]]
  435.         [-e[<equate file name>]]
  436.         [-f]
  437.         [-g]
  438.         [-h<header file name>]
  439.         [-i<INCLUDE directory list>]
  440.         [-k]
  441.         [-l[<listing file name>]]
  442.         [-m<small data offset>]
  443.         [-n]
  444.         [-o<object file name>]
  445.         [-p<page depth>]
  446.         [-q[<quiet interval>]]
  447.         [-s]
  448.         [-t]
  449.         [-w[<hash table size>][,<secondary heap size>]]
  450.         [-x[<listing file name>]]
  451.         [-y]
  452.         [-z[<debug start line>][,<debug end line>]]
  453.  
  454. These options can be given in any order.  Any parameter which is not
  455. a switch (denoted by a leading hyphen) is assumed to be a file name;
  456. up to three file names (assumed to be source, object, and listing file
  457. names respectively) can be given.  A source file name is always required.
  458. If a switch is being given a value, that value must immediately follow
  459. the switch letter with no intervening spaces.  For instance, to specify
  460. a page depth of 40 lines, the specification "-p40" should be used;
  461. "-p 40" will be rejected.
  462.  
  463. Switches perform the following actions:
  464.  
  465.      -d causes symbol table entries (hunk_symbol) to be written
  466.     to the object module for the use of symbolic debuggers.
  467.     If the switch is followed by a string of characters, only
  468.     those symbols beginning with that prefix string will be
  469.     written.  This can be used to suppress internal symbols
  470.     generated by compilers.  If the first character is an
  471.     exclamation mark (!), only symbols which do NOT begin
  472.     with the following characters are written out.
  473.  
  474.     Here are some examples:
  475.  
  476.         -d    writes all symbols
  477.         -dabc    writes only symbols beginning with "abc"
  478.         -d!x    writes symbols which do not begin with "x"
  479.  
  480.      -e causes an equate file (see above) to be produced.  A file
  481.     name can be specified; otherwise a default name will be used.
  482.  
  483.      -f causes any branches (Bcc, BRA, BSR) that could be converted
  484.     to short form to be flagged.  A68k will convert as many
  485.     branches as possible to short form (unless the -n switch is
  486.     is specified), but certain combinations of instructions may
  487.     set up a ripple effect where shortening one branch brings
  488.     another one into range.  This switch will cause A68k to
  489.     flag any branches that it may have missed; during pass 2
  490.     it is possible to tell this, although during pass 1 it might
  491.     not be.  If the -n switch (see below) is specified along
  492.     with this switch (suppressing all optimization), no branches
  493.     will be shortened, but all branches which could be shortened
  494.     will be flagged.
  495.  
  496.      -g causes any undefined symbols to be treated as if they were
  497.     externally defined (XREF), rather than being flagged as errors.
  498.  
  499.      -h causes a header file to be read prior to the source code file.
  500.     A file name must be given.  The action is the same as if the
  501.     first statement of the source file were an INCLUDE statement
  502.     naming the header file.  To find the header file, the same
  503.     directories will be searched as for INCLUDE files (see the
  504.     -i switch below).
  505.  
  506.      -i specifies directories to be searched for INCLUDE files in
  507.     addition to the current directory.  Several names, separated
  508.     by commas, may be specified.  No embedded blanks are allowed.
  509.     For example, the specification
  510.  
  511.         -imylib,df1:another.lib
  512.  
  513.     will cause INCLUDE files to be searched for first in the
  514.     current directory, then in "mylib", then in "df1:another.lib".
  515.  
  516.      -k causes the object file to be kept even if any errors were
  517.     found.  Otherwise, it will be scratched if any errors occur.
  518.  
  519.      -l causes a listing file to be produced.  If you want the listing
  520.     file to include a symbol table dump and cross-reference, use
  521.     the -x switch instead (see below).
  522.  
  523.      -m changes the assumed offset from the start of the DATA/BSS
  524.     section to the base register used when the small code /
  525.     small data option is activated by the NEAR directive.
  526.     If this parameter is not specified, the offset defaults
  527.     to 32768.
  528.  
  529.      -n causes all object code optimization (see above) to be disabled.
  530.  
  531.      -o allows the default name for the object code file (see above)
  532.     to be overridden.
  533.  
  534.      -p causes the page depth to be set to the specified value.
  535.     This takes the place of the PLEN directive in the Metacomco
  536.     assembler.  Page depth defaults to 60 lines (-p60).
  537.  
  538.      -q changes the interval at which A68k displays the line number
  539.     it has reached in its progress through the assembly.  The
  540.     default is to display every 100 lines (-q100).  Specifying
  541.     larger values reduces console I/O, making assemblies run
  542.     slightly faster.
  543.  
  544.     If you specify a negative number (e.g.     -q-10), line numbers
  545.     will be displayed at an interval equal to the absolute value
  546.     of the specified number, but will be given as positions
  547.     within the current module (source, macro, or INCLUDE) rather
  548.     than as a total statement count - the module name will also
  549.     be displayed.
  550.  
  551.     A special case is the value zero (-q0 or just -q) - this
  552.     will cause all console output, except for error messages,
  553.     to be suppressed.
  554.  
  555.      -s causes the object file to be written in Motorola S-record
  556.     format, rather than AmigaDOS format.  The default name for
  557.     an S-record file ends with ".s" rather than ".o"; this can
  558.     still be overridden with the -o switch, though.
  559.  
  560.      -t allows tabs in the source file to be passed through to the
  561.     listing file, rather than being expanded.  In addition, tabs
  562.     will be generated in the listing file to skip from the object
  563.     code to the source statement, etc.  This can greatly reduce
  564.     the size of the listing file, as well as making it quicker to
  565.     produce.  Do not use this option if you will be displaying or
  566.     listing the list file on a device which does not assume a tab
  567.     stop at every 8th position.
  568.  
  569.      -w specifies the sizes of fixed memory areas that A68k allocates
  570.     for its own use.  You should normally never have to specify
  571.     this switch, but it may be useful for tuning.
  572.  
  573.     The first parameter gives the number of entries that the hash
  574.     table (used for searching the symbol table) will contain.
  575.     The default value of 2047 should be enough for all but the
  576.     very largest programs.  The assembly will not fail if this
  577.     value is too small, but may slow down if too many long hash
  578.     chains must be searched.  The hashing statistics displayed by
  579.     the -y switch (see below) can be used to tune this parameter.
  580.     I've heard that you should really specify a prime number for
  581.     this parameter, but I haven't gone into hashing theory enough
  582.     to know whether it's actually necessary.
  583.  
  584.     The second parameter of the -w switch specifies the size (in
  585.     bytes) of the secondary heap, which is used to store nested
  586.     macro and INCLUDE file information (see below).  It defaults
  587.     to 1024, which should be enough unless you use very deeply
  588.     nested macros and/or INCLUDE files with long path names.
  589.  
  590.     You can specify either or both parameters.  For example:
  591.  
  592.         -w4093       secondary heap size remains at 1024 bytes
  593.         -w,2000      hash table size remains at 2047 entries
  594.         -w4093,2000  increases the size of both areas
  595.  
  596.     If you're really tight for memory, and are assembling small
  597.     modules, you can use this switch to shrink these areas below
  598.     their default sizes.  At the end of an assembly, a message
  599.     will be displayed giving the sizes actually used, in the form
  600.     of the -w command you would have to enter to allocate that much
  601.     space.  This is primarily useful to see how much secondary
  602.     heap space was used.
  603.  
  604.     NOTE: All other memory used by A68k (e.g. the actual symbol
  605.     table) is allocated as required (currently in 8K chunks).
  606.  
  607.      -x works the same as -l (see above), except that a symbol table
  608.     dump, including cross-reference information, will be added
  609.     to the end of the listing file.
  610.  
  611.      -y causes hashing statistics to be displayed at the end of the
  612.     assembly.  First the number of symbols in the table is given,
  613.     followed by a summary of hash chains by length.  Chains with
  614.     length zero denote unused hash table entries.  Ideally (i.e.
  615.     if there were no collisions) there should be as many chains
  616.     with length 1 as there are symbols, and there should be no
  617.     chains of length 2 or greater.  I added this option to help
  618.     me tune my hashing algorithm, but you can also use it to see
  619.     whether you should allocate a larger hash table (using the
  620.     first parameter of the -w switch, see above).
  621.  
  622.      -z was provided to help debug A68k itself.  It causes A68k to
  623.     list a range of source lines, complete with line number and
  624.     current location counter value, during both passes.  Lines
  625.     are listed immediately after they have been read from the
  626.     source file, before any processing occurs.
  627.  
  628.     Here are some examples of the -z switch:
  629.  
  630.         -z        lists all source lines
  631.         -z100,200    lists lines 100 through 200
  632.         -z100        lists all lines starting at 100
  633.         -z,100        lists the first 100 lines
  634.  
  635.  
  636. TECHNICAL INFORMATION
  637.  
  638.      The actual symbol table entries (pointed to by the hash table,
  639. colliding entries are linked together) are stored in 8K chunks which
  640. are allocated as required.  The first entry of each chunk is reserved
  641. as a link to the next chunk (or NULL in the last chunk) - this makes
  642. it easy to find all the chunks to free them when we're finished.  All
  643. symbol table entries are stored in pass 1.  During pass 2, cross-
  644. reference table entries are built in the same group of chunks,
  645. immediately following the last symbol table entry.  Additional chunks
  646. will continue to be linked in if necessary.
  647.  
  648.      Symbol names and macro text are stored in another series of linked
  649. chunks.  These chunks consist of a link pointer followed by strings
  650. (terminated by nulls) laid end to end.  Symbols are independent entries,
  651. linked from the corresponding symbol table entry.  Macros are stored as
  652. consecutive strings, one per line - the end of the macro is indicated by
  653. an ENDM statement.  If a macro spans two chunks, the last line in the
  654. original chunk is followed by a newline character to indicate that the
  655. macro is continued in the next chunk.
  656.  
  657.      Relocation information is built during pass 2 in yet another
  658. series of linked chunks.  If more than one chunk is needed to hold one
  659. section's relocation information, all additional chunks are released
  660. at the end of the section.
  661.  
  662.      The secondary heap is built from both ends, and it grows and
  663. shrinks according to how many macros and INCLUDE files are currently
  664. open.  At all times there will be at least one entry on the heap, for
  665. the original source code file.  The expression parser also uses the
  666. secondary heap to store its working stacks - this space is freed as
  667. soon as an expression has been evaluated.
  668.      The bottom of the heap holds the names of the source code file
  669. and any macro or INCLUDE files that are currently open.  The full path
  670. is given.  A null string is stored for user macros.  Macro arguments
  671. are stored by additional strings, one for each argument in the macro
  672. call line.  All strings are stored in minimum space, similar to the
  673. labels and user macro text on the primary heap.  File names are
  674. pointed to by the fixed table entries (see below) - macro arguments
  675. are accessed by stepping past the macro name to the desired argument,
  676. unless NARG would be exceeded.
  677.      The fixed portion of the heap is built down from the top.  Each
  678. entry occupies 16 bytes.  Enough information is stored to return to
  679. the proper position in the outer file once the current macro or
  680. INCLUDE file has been completely processed.
  681.      The diagram below illustrates the layout of the secondary heap.
  682.  
  683.     Heap2 + maxheap2 ----------->  ___________________________
  684.                       |                  |
  685.                       |   Input file table      |
  686.     struct InFCtl *InF ---------> |___________________________|
  687.                       |                  |
  688.                       |   Parser operator stack      |
  689.     struct OpStack *Ops --------> |___________________________|
  690.                       |                  |
  691.                       |   (unused space)      |
  692.     struct TermStack *Term -----> |___________________________|
  693.                       |                  |
  694.                       |   Parser term stack      |
  695.     char *NextFNS --------------> |___________________________|
  696.                       |                  |
  697.                       |   Input file name stack      |
  698.     char *Heap2 ----------------> |___________________________|
  699.  
  700.      The "high-water mark" for NextFNS is stored in char *High2,
  701. and the "low-water mark" (to stretch a metaphor) for InF is stored
  702. in struct InFCtl *LowInF.  These figures are used only to determine
  703. the maximum heap usage.
  704.  
  705.  
  706. AND FINALLY...
  707.  
  708.      Please send me any bug reports, flames, etc.  I can be reached
  709. on Mind Link (604/533-2312), at any meeting of the Commodore
  710. Computer Club / Panorama (PAcific NORthwest AMiga Association),
  711. or via Jeff Lydiatt or Larry Phillips.  I don't have the time
  712. or money to live on Compuserve or BIX, but my Usenet address is
  713. Charlie_Gibbs@mindlink.UUCP (...uunet!van-bc!rsoft!mindlink!a218).
  714.  
  715.  
  716.                 Charlie Gibbs
  717.                 2121 Rindall Avenue
  718.                 Port Coquitlam, B.C.
  719.                 Canada
  720.                 V3C 1T9
  721.